1. Field of the Invention
This invention relates to a documentation generation tool and, more particularly, to a documentation generation tool adapted to automatically extract comments from a variety of source files and specify the order in which those comments should appear in a produced output file. The invention also relates to a method of automatically generating documentation from a variety of source files.
2. Description of the Related Art
Engineers document the products they design by creating a variety of product documentation, each tailored to a specific readership. For any single product, product documentation might include the Internal Reference Specification (IRS), the External Reference Specification (ERS), the Hardware User's Guide (HUG), the Engineering Notes (EN), and the like. The IRS documents the product's operation for other company employees remaining largely confidential. The ERS similarly documents the product's operation excluding company confidential information. The ERS is widely distributed both inside and outside the company. The HUG details the product's hardware to the software. The EN often provides specific product implementation examples.
During the product's design, it is customary for engineers to include comments in the electronic files that describe their products. For example, firmware engineers include comments in a source code file describing the firmware's operation. The comments might include a definition of the variables used in a particular module as well as a description of how that module operates with other associated firmware modules. Similarly, electrical engineers include comments in the Hardware Description Language (HDL) source file describing a particular integrated circuit design. The comments might include a definition of the operation of a circuit block as well as a description of how that block relates to other circuit blocks.
Documentation tools are currently available that automatically extract these comments from their corresponding source files, for example, a firmware source code file or an HDL source file, and copy them onto a separate output file. A user then edits the output file to produce the desired product documentation be it an IRS, ERS, HUG, or EN. Examples of currently available documentation tools include Javadoc, Perlpod, LaTEX, and others.
Javadoc parses the declarations and documentation comments in a set of Java source files and produces a set of output pages describing details associated with the source code. Perlpod is a translator for the perl scripting language used to embed documentation within a no perl source code. LaTEX is a document preparation system for high-quality typesetting.
These documentation tools have a disadvantage in that they are highly dependent on the structure of the particular source file on which they operate. That is, these documentation tools do not operate on a variety of source files originating from a variety of design tools. For example, Javadoc operates exclusively on java source files extracting information from the java code itself as well as comments. Similarly, Perlpod operates exclusively on perl language source files. Moreover, these documentation tools do not have the ability to include web links, web pages, or other objects such as graphs and pictures in the generated output documentation.
Accordingly, a need remains for an automatic documentation generation tool that improves on the currently available tools.